Images (Media Cloud)
Gracenote Media Cloud is a commercial service that provides on-demand delivery of entertainment images to Gracenote customers. This service is based on a scalable and reliable Content Delivery Network (CDN) platform that has served billions of images.
Image URL Subdomain
Image references are included in many top-level API entities, e.g. Programs. Most image references are output as partial paths and must be prefixed with the Media Cloud subdomain to retrieve image content; exceptions are certain Celebrity Images
This is referenced below as <ClientSubdomain> and will be provided by the Gracenote team once the client is ready for production service. The api_key parameter is not used in the Production environment and will be ignored if included.
To download an image from the Media Cloud CDN use this format:
https://<ClientSubdomain>.tmsimg.com/<image URI>
Example: For the <URI>assets/p13755451_i_s4_af.jpg</URI>, prefix it with the base URL including your Media Cloud subdomain:
https://<ClientSubdomain>.tmsimg.com/assets/p13755451_i_s4_af.jpg
Contact your Gracenote representative for more information about your Media Cloud custom subdomain.
Image Download vs Passthrough Usage
For use cases that involve providing images at scale (such as display in end-user applications/devices), the images must be downloaded and served from the customer CDN. Direct/passthrough usage of Media Cloud from clients can be supported for smaller scale implementations but should be cached via e.g. a reverse proxy. Passthrough usage may incur overage fees depending on the individual commercial terms. Contact your Gracenote representative for more information about your Media Cloud usage limits.
Dynamic Image Resizing
API entity images reference the largest available image size. Media Cloud supports resizing of images which can be used to get smaller image sizes by specifying either w (width) or h (height) parameter:
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?h=300
https://demo.tmsimg.com/assets/p184852_i_h2_ag.jpg?w=400
It is not possible to change the aspect ratio by providing both parameters. If both parameters are provided, only the first one will be used. Dynamic resizing can add latency to the image call.
Managing Image Updates and Deletes
The API entities provide a full set of images in each entity update. The recommendation is to swap out the current set of assets with the incoming set. If your use case requires tracking image updates and/or deletions, use the following asset tag attributes:
<asset assetId="p13755451_i_s4_af" lastModified="2023-10-25T19:04:02Z" type="image/jpeg" width="3000" height="3000" primary="true" category="Iconic" ratio="1:1" tier="Series" expiredDate="2023-10-25T19:03:46Z"> <URI>assets/p13755451_i_s4_af.jpg</URI> </asset>
| Attribute | Guidelines |
|---|---|
| asset/@assetId | Update of the underlying image asset results in a new assetId |
| asset/@lastModified | Last modified date of image asset. If assetId is not changed, indicates a change in asset metadata |
| asset/@expiredDate | Expiration date of image, indicates the image is deprecated and should not be used past the date |
| asset/@updateId | Do not use |
| asset/@deleted | Do not use. Image delete is signaled either via removal of asset element or via expiredDate attribute |
Image updates are primarily signaled by a new assetId and a new lastModified date. The lastModified date may also change without changing the assetId if the other asset tag attributes change. Expired images include the expiredDate attribute and should not be used past the expiration date.
Image deletions are signaled implicitly either by the removal of the asset from the list or by setting the expiredDate. Typically the expiredDate is set on the day of the image deletion; the asset may remain in the list but will eventually be purged. The asset may also simply get removed from the list.
Image Types and Properties
For a table of supported image types and their properties see Image Types.
Image References
Image references are included in all top-level elements, with exception of Schedules and Venues. Image references are output as partial paths. You must preface these paths with your Media Cloud subdomain to retrieve image content. Contact your Gracenote representative for more information about your Media Cloud custom subdomain, if needed.
Program images are provided at a normalized program-specific level. For TV shows, this means that series-level and season-level images will only be included on the series program record (TMSIds beginning with SH). Series and season level images will not be repeated on each episode program record; the connectorId and seasonId on the episode should be used to link to the appropriate series/season level images. Episodes may contain their own episode-specific imagery.
Source images include TV station logos for the station itself, or if station is a local affiliate of broadcast or cable network, the network logo is included directly on the local station record.
Celebrity Images include standard headshots of celebrities.
Sports images for Organizations (leagues), Teams, and Universities represent standard logos for those entities. University logos are included once for each University and are not repeated within the Team record; college teams include a universityId reference which allows links to the appropriate university logo.
Handling Special Imagery
In addition to the default program images, Gracenote may provide special program images of the following types:
- Restricted (by a content provider)
- Branded (with a source/network logo)
- Market (specific to a country)
Gracenote enables special imagery through entitlements and provides these images, with distinguishing attributes alongside the default imagery. You can use these attributes preferentially or exclusively to select the special imagery. You may want to implement configurable parameters allowing you to update image preference rules without code changes. This makes it easier to support future changes in image selection logic as licensing agreements change.
Restricted Imagery
In some cases, Gracenote delivers certain restricted images from content providers. Restricted images are from a specific source/provider that wants them to be delivered only to customers with a contractual agreement to use these images. These images contain a specific string in the "provider" attribute of the asset tag. You can choose to parametrize, at a country level, the applicable provider string(s), as well as whether to prefer restricted imagery, or use it exclusively discarding default imagery, per provider.
Branded Imagery
Some sources provide Gracenote with program imagery containing their network logo. These images are available for use on the corresponding linear channels (network and affiliates). The images contain an <identifiers> block with the prgSvcIds of the linear channels in question. It is up to you to display these images. You can choose to parametrize, at a source or a country level, to prefer branded imagery or default imagery.
Market Imagery
Some sources provide Gracenote with imagery that differs in their market from the imagery Gracenote has collected, usually for the default market or first market in which the program was available or for which the program was produced. These images contain an <identifiers> block with the valid market. The customers should always use market over default imagery if available for the given country of the viewer.